Alpha Anywhere Federated Authentication - Authentication Using a SAML Identity Provider
Description
The Alpha Anywhere web security system supports login using a SAML identity provider (IdP) such as Active Directory, Okta, or Ping Identity. Authentication Using a SAML identity provider allows an application to use an organization's existing security infrastructure, allowing users to log in once and be authenticated with all apps used by the organization (single sign-on).
Overview
Federated authentication is a way to delegate authentication to another application, called an identity provider (commonly abbreviated IdP). A trust relationship is configured between applications in an organization and the identity provider. An application is configured to use an identity provider, and the identity provider is configured to allow an application to ask the identity provider to authenticate users. This allows a user to login once to the identity provider and be authenticated for all applications used by the organization configured to use the same identity provider (single sign-on). This is done in the same way as a typical application by redirecting to a login page. However, instead of the application redirecting to one of its own pages, the application redirects to the identity provider's login page. If the user is not already authenticated, the identity provider will authenticate the user by prompting for username and password, Windows integrated authentication, or any other way the identity provider is configured to authenticate a user. Once the user is authenticated, the identity provider redirects back to the application with an encrypted token containing the user's identity. Note that if the user had authenticated with identity provider from some other application, the identity provider does not need to reauthenticate and the encrypted token will be returned without any other prompting.
One important aspect of federated authentication is the identity provider does not need to be directly accessible to the application server. An organization's identity provider can be behind a company firewall while the application runs in Alpha Cloud. Users log into the company VPN, giving them access to the identity provider. When the Alpha Cloud app needs to authenticate the user, the app will redirect to the identity provider, which the user's browser has access to. Next, the identity provider authenticates the user. If authentication succeeds, the identity provider redirects with an encrypted token back to the Alpha Cloud app. The app validates the encrypted token and finally logs the user in to the app.
When using the "federated authentication" feature, the Alpha Anywhere web security system is still used. If the identity provider returns user roles (a.k.a "groups") along with the user name in the encrypted token, those roles can be used by the Alpha Anywhere security system. Otherwise, the authenticated user must be in the Alpha Anywhere security system with the roles the user is a member of. The federated authentication configuration can be set to automatically add a user that is not in the Alpha Anywhere security system in which case the default role(s) defined in the security system will be assigned to the user. If roles are not included in the encrypted token and the application is not configured to automatically add new users, the user must be manually added to the application as they normally would be without federated authentication being enabled.
Configuring the System to Use Federated Authentication
Step 1 - Enable federated authentication in the web application's security settings
The security settings dialog has a new option for Federated Authentication settings. Click on the "..." button to enable federated authentication and set other federated authentication options.
Required pages
Federated authentication settings has a number of pages that are used at different points in the authentication workflow.
Federated Login Page - This page is used by the federated login workflow. It will initiate a login and process the response from an identity provider.
Federated Logout Page
Federated Login Error Page - This page is displayed when federated login fails.
Federated XHR Reauthentication Page - This page is a code only page. There is no HTML to customize. However, there is a JSON response payload that can be changed to customize the message that is displayed during authentication and width and height CSS that will be used if the federated authentication timeout page iframe (see below) needs to be displayed.
Federated Authentication Timeout Page - This page is used when the user's login has expired and there hasn't been a timely response attempting to reauthenticate automatically during an XHR. This page will be shown in an iframe so the state of the application won't be affected on successful reauthentication.
Federated XHR Reauthentication Complete Page - This page will be displayed in the federated timeout page iframe (see above) when reauthentication has been successful.
Required Xbasic modules
Federated authentication uses Xbasic modules to implement the authentication workflow, selected protocol, and tenant selection (in a multi tenant application).
Federated authentication module - This module contains the code for handling federated authentication. This module will use the SAML Xbasic module and the Application tenant Xbasic module.
SAML Xbasic module - This module contains the code for creating requests to a SAML identity provider and for handling responses from a SAML identity provider.
Application tenant Xbasic module - This module contains one exported function getTenantId() that returns a tenant id of type C. This can be a hardcoded value if the application is not multi-tenant. The tenant id is used to lookup the identity provider configuration in the federated authentication configuration database.
Step 2 - Set up federated authentication
Setting up federated authentication (Step 2) and Configuring the identity provider for you Alpha Anywhere application (Step 3) will typically require you to go back and forth between the two steps. Your application (the "Relying Party" in SAML terminology) will need to know the URL for sending requests to the identity provider, and the identity provider will need to be set to allow your application to send requests to it. The Federated Authentication Setting dialog has a button on it to View/Create Federated Authentication Configuration Table Settings. This table will be used to store the information about the SAML identity provider used by your application. This table has a "tenantId" column so that more than one identity provider can be used by your application if your application is a multi-tenant application. You will need to use this button to create that table. The Federated Authentication Settings dialog also has a button creating a UX for managing the data in the Federated Authentication Configuration Table. This UX can be in your application or in a separate, operational application. Either way, it is recommended to use this UX as it will make managing the SAML configuration data much easier. Since it is a UX you are free to customize it. Once this is done, proceed to Step 3. Step 3 will direct you back here to use the identity provider metadata URL.
Configuration name
The name you want to give to this configuration.
Relying party id
This is the identifier passed to the identity provider that tells it what configuration it should use to handle the request and create a response. This is optional. If left blank the deployed application's base URL will be used.
Tenant id
The tenant id if used in multi-tenant application. This allows you to associate this configuration with a specific tenant and will be used at login time to determine which configuration to use. If the application is not a multi-tenant application, leave the default value of "Default".
Publish application federation metadata
Allowing the publish of federation metadata from the application will allow an identity provider to configure itself for use with the application. This is usually a one time operation unless requests are signed and/or encrypted which would require the identity provider to have certificates from the application. This typically isn't needed since requests should be sent over https. If enabled the metadata will be available at <application's base url>/saml/FederationMetadata.xml.
Configuration status
Indicate whether this configuration is available for use.
Use identity provider federation metadata URL
Identity provider federation metadata URL
Indicate where to fetch identity provider configuration from the identity provider allowing for automatic configuration. It is recommended to use this together with the Monitor identity provider metadata option.
Download IdP Metadata Now
Click on this button to download the identity provider's metadata now.
Monitor identity provider metadata
Identity provider configuration may change. Specifically, identity provider configuration may change during certificate rollover. Select this option to monitor the identity provider metadata for changes so that updated certificates will automatically be using without interruptions to the application's availability. It is recommended that this is enabled as it will allow a more hands off way of handling certificate updates with zero to minimal operational downtime.
Monitor frequency
How often should the identity provider's federation metadata be checked.
Identity provider URL
The URL used to request federated authentication.
Identity provider logout URL
The URL used to logout. SAML defines 3 response types: POST, Redirect, and Artifact. Alpha Anywhere supports POST and Redirect. The identity provider must be configured for POST or Redirect.
Response type
SAML defines 3 response types: POST, Redirect, and Artifact. Alpha Anywhere supports POST and Redirect. The identity provider must be configured for POST or Redirect.
Signing certificates thumbprints
The hexadecimal thumbprint of signing certificates. More than one certificate may be used for signing in order to support certificate rollover. Enter each thumbprint on a new line. If responses are signed, Signing Certificates Thumbprints or Signing Certificates must be specified in order to validate the signature.
Signing certificates
The base64 encoded signing certificates. More than one certificate may be used for signing in order to support certificate rollover. Enter each base64 encoded certificate on a new line. If responses are signed, Signing Certificates Thumbprints or Signing Certificates must be specified in order to validate the signature.
Roles source
Indicate where to find a user's roles/groups. Application means roles/groups for a user are retrieved from the applications security data. Claims means the user's roles/groups come with the identity provider token for the authenticate user.
Automatically add user to security data
When this option is selected user ids that are not found in the security database will be automatically added along with the default security group defined in the security settings Customize Options tab.
Role Claim Attributes
SAML attribute name(s) that contain a user's claims. This may be a CrLf list of attribute names. The value of first attribute found will be used. The attribute name(s) can be gotten from the identity provider.
Add Group Name Map Entry
Add an entry to the group name map list.
Group Names Map
When the user's roles/groups are claims in the identity provider's authentication token, it may be necessary to map the claim to an application role/group. Use this table to provide that mapping.
Overlay Title
Text to be shown if authentication needs to be done during an XHR. This defaults to "authenticating".
Time to wait before showing login page
If authentication is needed during an XHR, an attempt is made to do the authentication automatically. However, an identity provider may require user credential entry (user name and password), or an error may have occurred. This setting is the time to wait for a successful authentication. If that time elapses, a UI is displayed to show the identity provider login page or error information.
Width CSS
The height of the login/error UI in CSS units.
Height CSS
The width of the login/error UI in CSS units.
The federated authentication configuration UX contains a list of all the defined identity providers and a form for creating/editing them. Each identity provider configuration is identified by a unique tenantId.
When creating or editing an identity provider's configuration, the identity provider's SAML metadata URL can be used to automatically fill in the identity provider specific prompts. This is the recommended way to set the identity provider's configuration as it will be the most accurate way to do so.
Step 3 - Configure the Identity Provider for an Alpha Anywhere Application
Follow your identity provider's documentation for setting it up for use by a Relying Party. Among other things, an identity provider typically needs to be configured to allow requests from a "Relying Party", which is your application. The request to the identity provider from your application will contain a URL for being redirected back to your application. This URL will process the response from the identity provider in your application. An example URL is https://www.foofoorabbit.com/federatedAuthentication.a5w. This URL will need to be in the identity provider's white list of redirect URLs or "Allowed Redirect URLs". If you have different deployments of your application for development and testing, those URLs will need to be added too. Or you may set up a separate security application in the identity provider for development and testing. Once you have configured the identity provider, you can use an identity provider metadata URL to more easily setup federated authentication (Step 2) in your application.
Diagnostics
Errors that occur during the federated authentication workflow will be written to the Xbasic error log. In addition to this, tracing the authentication workflow can be enabled by setting a session variable Context.Session.Variables.FederatedAuthLogLevel = "Trace". The trace messages will be written to the Alpha Anywhere trace facility as is done with the Xbasic trace.writeln("message", "trace file or pane"). The trace files will be named Trace_FederatedAuthentication.log and Trace_SAML.log. As this is enabled through a session variable, it is enabled on a per user basis, and you will need have a page or control on a component to set and/or clear the session variable. A UX template named FederatedAuthentication-Diagnostic Settings can be used to create a UX with a control to enable/disable tracing.